using System;
using System.Collections;
using System.Web;

namespace Sedna.Core.Controller
{
	/// <summary>
	/// base interface for every action in the WebUI Framework controller.
	/// Every action must accept an instance of HttpContext and an instance of 
	/// ExecutionContext. It is guaranteed by the IActionExecutor (or any other action caller)
	/// that neither httpContext parameter, nor executionContext parameter equals to null.
	/// However, since Developers encouraged not to use httpContext parameter directly, since this
	/// complicates the isolated testing immensely. Therefore, httpContext parameter can be null
	/// in case of an isolated testing scenario, even through Developers need not check this parameter for 
	/// null, since an Action that uses HttpContext directly cannot be tested in isolated envoronment.
	/// </summary>
	public interface IAction
	{
		/// <summary>
		/// a list of <see cref="IActionParam"/> instances
		/// </summary>
		IList ActionParams
		{
			get;
			set;
		}

//		[Obsolete("in favour of Execute(HttpContext, IExecutionContext)")]
//		IActionResult Execute(HttpContext httpContext, IDictionary executionContext);

		/// <summary>
		/// a main and the only method that must be implemented by a Developer
		/// This method should perform any business calculations (though Developers encouraged 
		/// to move all the business login down to Sedna.Base), database interactions or URL redirections.
		/// Although it is technically possible to mix all the logic types (e.g. business and 
		/// redirection, i.e. navigation), Developers are strongly discourage from doing so.
		/// They should split this type of functionality in separate actions and use action chaining instead.
		/// Besides, there are a set of default (or 'standard') actions that perform URL redirection
		/// (such as <seealso cref="Sedna.Core.Controller.Menu.UrlRedirectMenuAwareAction"/>), 
		/// which should be used instead of hardcoding this into one's separate custom action
		/// </summary>
        /// <param name="executionContext">An instance of a IExecutionContext representing a current ExecutionContext for a request. This parameter is never null.</param>
		/// <returns>
		/// An instance of an IActionResult that contains a status, which is essensially 
		/// a string that represents the next hop if it can be located within a current configuration.
		/// Those who implement an action should use special convenience methods (<see cref="Sedna.Core.Controller.Common.AbstractAction.CreateResult"/>).
		/// </returns>
		IActionResult Execute(IExecutionContext executionContext);

	    /// <summary>
	    /// This metho is called before action execution. If it returns false, action will not be executed.
	    /// </summary>
        /// <param name="executionContext">An instance of a IExecutionContext representing a current ExecutionContext for a request. This parameter is never null.</param>
	    /// <returns>false if action should not be executed, otherwise true</returns>
        bool CanExecute(IExecutionContext executionContext);
	    
		/// <summary>
		/// defines an optional error code of a SednaException instance that is thrown in 
		/// case any unhandled exception is thown during the action execution.
		/// the default value must be 0, which means that no SednaException to be thrown and 
		/// the source exception is proparaged or handled using the corresponding exception handling and matching mechanism
		/// </summary>
		int ErrorCode
		{
			get;
		}
	    
	}
}
